ATSUSetSoftLineBreak

OSStatus ATSUSetSoftLineBreak (
ATSUTextLayout iTextLayout,
UniCharArrayOffset iLineBreak);

iTextLayout

A reference of type ATSUTextLayout. Pass a reference to an initialized text layout object. You cannot pass NULL for this parameter.

iLineBreak

A value of type UniCharArrayOffset. Pass the edge offset that corresponds to the soft line break you want to set. To indicate the beginning of the text buffer, pass the constant kATSUFromTextBeginning, described in Text Offset Constant. If the offset is outside the text buffer, ATSUSetSoftLineBreak returns the result code kATSUInvalidTextRangeErr.

function result

A result code. See Result Codes.

DISCUSSION

The ATSUSetSoftLineBreak function enables you to use your own line-breaking algorithm to set soft line break positions in a range of text. You should call ATSUSetSoftLineBreak to implement word break hyphenation. If you do not want to set line breaks, call the function ATSUBreakLine and pass true for the iUseAsSoftLineBreak parameter.

Before calculating soft line breaks, ATSUSetSoftLineBreak turns off any previously set line justification, rotation, width alignment, descent, and ascent values and treats the text as a single line. It then examines the text layout object to make sure that the style runs cover the entire range of text. If there are gaps between style runs, ATSUSetSoftLineBreak assigns the characters in the gap to the style run following the gap. If there is no style run at the beginning of the range of text, ATSUSetSoftLineBreak assigns these characters to the first style run it can find. If there no style run at the end of the range of text, ATSUSetSoftLineBreak assigns the remaining characters to the last style run it can find.

After calling ATSUSetSoftLineBreak, you should call the function ATSUMeasureText to measure the text.

SPECIAL CONSIDERATIONS

ATSUSetSoftLineBreak may allocate memory in your application heap, unless you designate a different heap by calling the function ATSUCreateMemorySetting.

VERSION NOTES

Available beginning with ATSUI 1.0.